home *** CD-ROM | disk | FTP | other *** search
/ TeX 1995 July / TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO / macros / lollipop / lollipop.hqx / Lollipop Manual / extern.tex < prev    next >
Text File  |  1992-11-18  |  11KB  |  296 lines
  1. % Extern.tex copyright 1992 Victor Eijkhout
  2. %
  3. \Chapter[chap:referencing]
  4. Referencing
  5.  
  6. In manuals and scientific documents you often want to write something
  7. like `see Chapter~4'. But what if you shuffle the chapters a bit? It
  8. would be nice if the number would be updated automatically. With
  9. \Lollipop, as with many other \TeX\ macro packages, this is easily
  10. done.
  11.  
  12. Here is an example to set the mood for the rest of this chapter.
  13. The sort of thing that is referred to most is a heading. So suppose
  14. you want to refer to a section number.
  15.  
  16. \Example
  17. \DefineHeading:TestSection
  18.  line:start Style:italic TestSectionCounter Spaces:2 title
  19.  line:stop Stop
  20. \TestSection[one:section?] First section\par
  21. After this section will come section~\ref[other:section!].
  22.  
  23. \TestSection[other:section!] Another section\par
  24. This is the section that came after section~\ref[one:section?].
  25. \ExampleStop
  26.  
  27. \Section What and how do you reference?
  28.  
  29. You can reference not only headings but everything that has a
  30. counter. Thus all generic constructs can be referenced, and in
  31. addition you can reference item numbers in a list (there are examples
  32. of this latter possibility in section~\ref[sec:bib]). The simplest way
  33. of referencing something is to put the key in square brackets behind
  34. it:
  35.  
  36. \Ver>\Section[this:section] The title of This Section<Rev
  37. The key is used by typing
  38. \Ver>\ref[this:section]<Rev
  39.  
  40. As you may have guessed from the above examples, keys can contain all
  41. sorts of characters. Only brackets, braces, and the hash sign are
  42. excepted. You get an error message if you try to use the same key
  43. twice.
  44.  
  45. Another way of declaring a key is to use the command \refcs{label}
  46. carrying the key
  47. \Ver>\label[the:key]<Rev
  48. This can be useful if you want to declare two keys for a single
  49. reference. Make sure that the \cs{label} command is not part of the
  50. title. Unexplained phenomena occur if you do that. Instead put the
  51. label after the construct you want to reference:
  52. \Ver>\Section Precautions and remedies
  53.  
  54. \label[sec:precautions]\label[sec:remedies]
  55. In this section ...<Rev
  56.  
  57. \Section[sec:shape:reference] The shape of the reference
  58.  
  59. By default, a reference consists of just the number of the thing you
  60. reference. You can customize the way an object is referenced by using
  61. the option \refopt{label} in its definition. For instance, often you
  62. want things like parentheses around references. Putting this
  63. information in the label definition saves you a lot of work in case
  64. you change your mind later.
  65.  
  66. \Example
  67. \DefineHeading:TestSection
  68.  line:start Style:italic TestSectionCounter Spaces:2 title line:stop
  69.  label:start ( TestSectionCounter ) label:stop Stop
  70. \TestSection[one:section?2] First section\par
  71. After this section will come section~\ref[other:section!2].
  72.  
  73. \TestSection[other:section!2] Another section\par
  74. This is the section that came after section~\ref[one:section?2].
  75. \ExampleStop
  76.  
  77. Another use of customized labels is including other counters in the
  78. reference:
  79.  
  80. \Example
  81. \DefineHeading:TestChapter 
  82.  line:start Style:bold TestChapterCounter / title line:stop Stop
  83. \DefineHeading:TestSection
  84.  line:start Style:italic TestSectionCounter Spaces:2 title line:stop
  85.  label:start TestChapterCounter . 
  86.              TestSectionCounter label:stop Stop
  87. \TestChapter First chapter\par
  88. Pretty short chapter
  89. \TestChapter Second chapter\par
  90. \TestSection[one:section?3] First section\par
  91. After this section will come section~\ref[other:section!3].
  92.  
  93. \TestSection[other:section!3] Another section\par
  94. This is the section that came after section~\ref[one:section?3].
  95. \ExampleStop
  96.  
  97. A more surprising application of explicit definition of labels is
  98. inclusion of the title in the reference.
  99. \Example
  100. \DefineHeading:TestSection
  101.  line:start Style:italic TestSectionCounter Spaces:2 title line:stop 
  102.  label:start TestSectionCounter literal: Spaces:1 
  103.              Style:italic title label:stop Stop
  104. \TestSection[one:section?4] First section\par
  105. After this section will come section~\ref[other:section!4].
  106.  
  107. \TestSection[other:section!4] Another section\par
  108. This is the section that came after section~\ref[one:section?4].
  109. \ExampleStop
  110.  
  111. \Section[sec:ref-local] Local references
  112.  
  113. Some documents are
  114. collated out of parts that were documents in themselves. 
  115. The \Lollipop\ command \cs{InputFile} facilitates in a number
  116. of ways working with such a segmented file (see
  117. section~\ref[sec:InputFile]). One of the problems with input files is
  118. that in such a case it may happen that the same reference key is used
  119. in more than one part of the document. This phenomenon is
  120. not at all unknown in multiple authored documents. Ordinarily this
  121. would result in incorrect references.
  122.  
  123. To prevent such collisions \Lollipop\ can use local
  124. references: the command \refcs{LocalReferences} has default \n{no},
  125. and specifying 
  126. \Ver>LocalReferences:yes<Rev
  127. creates local \file{aux} files for each input file.
  128.  
  129. \Section[sec:bib] Bibliography citations
  130.  
  131. \Lollipop\ has as yet no separate facilities for bibliographies such
  132. as an interface to Bib\TeX. However, since a bibliography is just a
  133. list, referencing items in it is quite easy.
  134.  
  135. \Example
  136. \DefineList:BibList item:left [ itemCounter ] item:stop
  137.  label:start [ itemCounter ] label:stop Stop
  138. In this example we shall have occasion to refer to 
  139. \ref[Abee80] and~\ref[Ceede79].\par
  140. \Indent:no Bibliography
  141. \BibList \item[Ace55] C.D. Ace, Inscrutible title.
  142. \item[Abee80] E.F. Abee, Worthless drivel.
  143. \item[Ceede79] G.H. Ceede, Contractual obligation.
  144. \>
  145. \ExampleStop
  146.  
  147. Here is a way to customize the label (if you need to refresh your
  148. memory about description lists, see
  149. section~\ref[sec:description:list]).
  150.  
  151. \Example
  152. \DefineList:BibList item:left [ itemCounter ] item:stop
  153.  label:start ( description ) label:stop Stop
  154. In this example we shall have occasion to refer to 
  155. \ref[Abe80] and~\ref[Ceedee79].\par
  156. \Indent:no Bibliography
  157. \BibList \item[Aace55] Aace55
  158. C.D. Aace, Inscrutible title.
  159. \item[Abe80] Abe80
  160. E.F. Abe, Worthless drivel.
  161. \item[Ceedee79] Ceedee79
  162. G.H. Ceedee, Contractual obligation.
  163. \>
  164. \ExampleStop
  165.  
  166. \Chapter[chap:external-files] External Files
  167.  
  168. Some document require information to be collected during a run. Such
  169. information typically is a table of contents or index, and it is
  170. gathered in an external file. (The reason for gathering such
  171. information in a file at all is that often some external manipulation,
  172. for instance sorting of an index, is needed.) Since there are many
  173. possibilities for external files (mathematical monographs may have a
  174. list of definitions, or a list of notations) \Lollipop\ does not
  175. predefine such files, but supplies all of the tools for creating them.
  176.  
  177. External files involve four actions: 
  178. \Enumerate\item The file should be declared.
  179. \item It should be specified what information is to be written to the
  180. file.
  181. \item The formatting of the contents of the file has to be specified.
  182. \item The file has to be loaded.
  183. \>
  184.  
  185. \Section Declaring and loading an external file
  186.  
  187. The first act, declaring the existence of the external file is very
  188. easy with the command \refcs{DefineExternalFile}:
  189.  an internal name and a three-character file name extension have
  190. to be given as parameters.
  191. \Ver>\DefineExternalFile:contents=toc<Rev
  192. With this definition, if the document is called \file{book.tex} then
  193. the `contents' will be gathered in a file called \file{book.toc}.
  194.  
  195. For each external file \n{Foo} there is a command to determine whether
  196. that file will be regenerated in the next run of \TeX:
  197. \refcs{WriteFoo} with values \n{yes}/\n{no} will allow or prevent the
  198. file being regenerated. The value \opt{yes} is default. The
  199. command \refcs{WriteExtern} (values \n{yes}/\n{no})
  200. can be used to prevent writing out any external files (including the
  201. \file{.aux} file that keeps track of references).
  202.  
  203. The final act, loading an external file, is as easy as declaring it:
  204. use \refcs{LoadExternalFile} as in
  205. \Ver>\LoadExternalFile:contents<Rev
  206. This does not cause any page breaks or headings to be set over the
  207. loaded material, so you have to do that explicitly.
  208.  
  209. \Section[sec:ext-option] Generating external files
  210.  
  211. Next, macros that write to the table of contents have to declare this
  212. information. The \refopt{external} option is used for this.
  213. Any counter that the construct has will be written out
  214. automatically, and the style designer usually has to specify only
  215. that the title will be written out.
  216. \Ver>\DefineHeading:Section
  217.     [...]
  218.     external:contents title external:stop<Rev
  219.  
  220. There is no objection to a construct writing information to more than
  221. one external file.
  222.  
  223. \Section[sec:ext-item] Formatting an external file
  224.  
  225. The hardest part is declaring the formatting of an external file. For
  226. this a separate generic construct exists: the `external item' with
  227. defining command \refcs{DefineExternalItem}. For example, if
  228. \cs{Section} writes to \n{contents}, than an external item \n{Section}
  229. corresponding to this file has to be declared. The option
  230. \refopt{file} is use to declare to which file the external item
  231. belongs. This way the same name can be reused for more than one file.
  232.  
  233. \Ver>\DefineExternalItem:Section file:contents
  234.     [...] Stop<Rev
  235.  
  236. An external item is basically a list with just one item. Thus, the
  237. option \refopt{item} is available. The elements of an external item are
  238. the label (the counter value), the page number where the information
  239. was generated, and the title. 
  240. For the label (say for a construct \cs{Foo})
  241. an option \refopt{FooLabel} is created.
  242. Thus the typical formating looks like
  243. \Ver>\DefineExternalItem:Chapter file:contents
  244.     item:left ChapterLabel item:stop
  245.     title begingroup Spaces:2 Style:italic Page endgroup
  246.     Stop<Rev
  247. In fact, a control sequence \refcs{FooLabel} is created, which
  248. can be used in other external items.
  249.  
  250. Since an external item is a list in itself, you have to pull a
  251. certain trick to get items for subsections to indent further than
  252. those for sections. This is what the command \cs{PushIndentLevel} was
  253. designed for.
  254.  
  255. A typical indented item looks like:
  256. \Ver>\DefineExternalItem:SubSection file:contents
  257.     PushIndentLevel PushIndentLevel
  258.     item:left SectionLabel . SubSectionLabel item:stop
  259.     title begingroup Spaces:2 Style:italic Page endgroup
  260.     Stop<Rev
  261.  
  262. \Section Example
  263.  
  264. The following example is for a typical table of contents that
  265. records sections and subsections. In good old-fashioned style, the
  266. subsections are indented with respect to the sections.
  267.  
  268. \Example
  269. \DefineExternalFile:TheContents=tct
  270. \DefineHeading:TestChapter Style:bold
  271.  line:start TestChapterCounter Spaces:2 title line:stop
  272.  external:TheContents title external:stop Stop
  273. \DefineExternalItem:TestChapter file:TheContents
  274.  item:left Style:bold TestChapterLabel item:stop title white:5pt
  275.       Page par Stop
  276. \DefineHeading:TestSection Style:italic
  277.  line:start TestChapterCounter . TestSectionCounter 
  278.             Spaces:2 title line:stop
  279.  external:TheContents title external:stop Stop
  280. \GoverningCounter:TestSection=TestChapter
  281. \DefineExternalItem:TestSection file:TheContents PushIndentLevel
  282.  item:left Style:bold TestChapterLabel . TestSectionLabel item:stop 
  283.  title white:5pt Page par Stop
  284.  
  285. \LoadExternalFile:TheContents
  286. \TestChapter First heading\par
  287. \TestSection First subheading\par
  288. Some text might be nice.
  289. \TestSection Second subheading\par
  290. Some more text.
  291. \TestChapter Second heading\par
  292. \TestSection Third subheading\par
  293. Yet more text.
  294. \TestSection Fourth subheading\par
  295. And again: text.
  296. \ExampleStop